<html>
<head>
<link href="../style/style.css" rel="stylesheet" type="text/css">
</head>
<body>
<p class="heading">
Keyboard Module (last update 13/05/01)
</p>
<p class="subheading">
Description:
</p>
<p>
This module adds keyboard support to the gamelib library. As of 29/05/2001 keyboard support
for UNIX platforms has been added! Thanks to Ralf Berkvens
(<a href="mailto:ralf@ilse.nl">ralf@ilse.nl</a>) for his advice on trapping keyboard events on
unix platforms. So keyboard-controlled games will now work with Windows, Mac, Sun, Linux,
FreeBSD, etc etc (oh and IRIX - a little known platform still used by a small rabble of
disturbingly dedicated followers :-)
</p>
<p class="subheading">
To use:
</p>
<p>
The code can be linked in to your script by adding this line to the &lt;HEAD&gt; section of
your document:
</p>
<p class="jcode">
&lt;script language="Javascript" src="gamelib_keyboard.js"&gt;&lt;/script&gt;
</p>
<p>
The keyboard module is the easiest to use by far. To trap a key, just add something like:
</p>
<p class="jcode">
upKey=Kb_trapkey("q")
</p>
<p>
From this point on, whenever the q key is pressed, it will alter a property
of upKey. The case is not relevent. For games use, it's not important whether
you have caps-lock on or off, and so "Q"="q". If q is pressed, upKey.pressed
will equal true, otherwise it will equal false. So if your game needed to check
whether q was pressed, you'd do something such as:
</p>

<p class="jcode">
if(upKey.pressed){<br>
&nbsp; // do something<br>
}<br>
</p>

<p>
If you prefer a more Event Driven approach to coding, then you can use the new setEvent
and clearEvent methods for keys. With these, you can tell a key what to do when it's
pressed! So if you wanted your game/script to call the function called myFunc() when
key "F" was pressed, you'd do this:
</p>

<p class="jcode">
upKey=Kb_trapkey("f");<br>
upKey.setEvent("myFunc()");
</p>

<p>
Both approaches have advantages and disadvantages. The first method is by far the best
when you are already using a central loop, and can check the keys during the game. The
second is better for menus etc. <a href="#setEvent">See the docs below</a> for more details...
</p>

<p>
If you are developing a game for Internet Explorer only, you can also trap the ESC,
CTRL and SHIFT keys, and also the LEFT,RIGHT,UP and DOWN cursor keys by passing their
name into the keytrapping function. So if you wished to trap the SHIFT key, you'd use this:
</p>

<p class="jcode">
shiftKey=Kb_trapkey("SHIFT")
</p>

<p>
For Netscape 4/6, the following mappings are used instead of the special keys:
</p>

<p>
UP = I, DOWN = K, LEFT = J, RIGHT = L, CTRL = Z, SHIFT = A
</p>

<p>
(What this means is, if you trap the SHIFT key, then people playing your game with
Netscape will use key A instead of the shift key. This is because Netscape doesn't
register key events with the special keys.)
</p>


<p class="subheading">
Descriptions of methods
</p>

<table>
<tr>
<th>Method</th><th NOWRAP>Parameters</th><th>Description</th>
</tr>
<tr>
<a name="setEvent">
<td>setEvent</td><td>String</td><td>
This method associates an event with a keypress. The string is
usually a function to be called, but can be any valid javascript
statement. Be aware that events occur when the key is pressed
down, and will be triggered again if the key repeats (when held
down.) It's not a good idea to use this method for real-time
input in action type games. It is a good idea to use it for
menus or other navigation interfaces, where you don't want to
have to set up a loop, or <a href="coredoc.html#GLhook">hook</a>
into the gamelib timer.
</td>
</tr>
<tr>
<a name="clearEvent">
<td>clearEvent</td><td>(none)</td><td>Cancels the event associated with a key.
</td>
</tr>
</table>


<p class="subheading">
List of Global properties
</p>

<p>
<a href="#KBlastkey">Kb_lastkey</a><br>
</p>


<p class="subheading">
Descriptions of Global properties
</p>

<table>
<tr>
<th>Property</th><th NOWRAP>Data Type</th><th NOWRAP>Read/Write<th>Description</th>
</tr>
<tr>
<a name="">
<td>Kb_lastkey</td><td>Object</td><td>R/W</td><td>
<p>
This variable holds the last key pressed. It holds the key trapping object you created
to make things easier for testing. So if you wanted to test if the up key (as defined
above) was the last key pressed, you'd do the following:
</p>
<p class="jcode">
if(Kb_lastkey==upKey){<br>
&nbsp; // do something<br>
}<br>
</p>
</td>
</tr>
</table>

</body>
</html>